Language/OS - Multiplatform Resource Library

home *** CD-ROM | disk | FTP | other *** search

/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / pcl / docs.lha / cmu-user / cmu-user.info-7 < prev next >

Wrap

Text File | 1992-08-05 | 51KB | 1,381 lines

Info file: cmu-user.info, -*-Text-*- produced by latexinfo-format-buffer from file: cmu-user.tex File: cmu-user.info Node: Representation Efficiency Notes, Prev: Efficiency Notes and Type Checking, Up: Efficiency Notes, Next: Verbosity Control Representation Efficiency Notes ------------------------------- When operating on values that have non-descriptor representations (*Note Non-Descriptor Representations::), there can be a substantial time and consing penalty for converting to and from descriptor representations. For this reason, the compiler gives an efficiency note whenever it is forced to do a representation coercion more expensive than efficiency-note-cost-threshold ?. Inefficient representation coercions may be due to type uncertainty, as in this example: (defun set-flo (x) (declare (single-float x)) (prog ((var 0.0)) (setq var (gorp)) (setq var x) (return var))) which produces this efficiency note: In: DEFUN SET-FLO (SETQ VAR X) Note: Doing float to pointer coercion (cost 13) from X to VAR. The variable `var' is not known to always hold values of type `single-float', so a descriptor representation must be used for its value. In sort of situation, and adding a declaration will eliminate the inefficiency. Often inefficient representation conversions are not due to type uncertainty -- instead, they result from evaluating a non-descriptor expression in a context that requires a descriptor result: * Assignment to or initialization of any data structure other than a specialized array (*Note Specialized Arrays::), or * Assignment to a `special' variable, or * Passing as an argument or returning as a value in any function call that is not a local call (*Note Interactions With Local Call::.) If such inefficient coercions appear in a "hot spot" in the program, data structures redesign or program reorganization may be necessary to improve efficiency. See sections *Note Block Compilation::, *Note Numbers:: and ?. Because representation selection is done rather late in compilation, the source context in these efficiency notes is somewhat vague, making interpretation more difficult. This is a fairly straightforward example: (defun cf+ (x y) (declare (single-float x y)) (cons (+ x y) t)) which gives this efficiency note: In: DEFUN CF+ (CONS (+ X Y) T) Note: Doing float to pointer coercion (cost 13), for: The first argument of CONS. The source context form is almost always the form that receives the value being coerced (as it is in the preceding example), but can also be the source form which generates the coerced value. Compiling this example: (defun if-cf+ (x y) (declare (single-float x y)) (cons (if (grue) (+ x y) (snoc)) t)) produces this note: In: DEFUN IF-CF+ (+ X Y) Note: Doing float to pointer coercion (cost 13). In either case, the note's text explanation attempts to include additional information about what locations are the source and destination of the coercion. Here are some example notes: (IF (GRUE) X (SNOC)) Note: Doing float to pointer coercion (cost 13) from X. (SETQ VAR X) Note: Doing float to pointer coercion (cost 13) from X to VAR. Note that the return value of a function is also a place to which coercions may have to be done: (DEFUN F+ (X Y) (DECLARE (SINGLE-FLOAT X Y)) (+ X Y)) Note: Doing float to pointer coercion (cost 13) to "<return value>". Sometimes the compiler is unable to determine a name for the source or destination, in which case the source context is the only clue. File: cmu-user.info Node: Verbosity Control, Prev: Representation Efficiency Notes, Up: Efficiency Notes Verbosity Control ----------------- These variables control the verbosity of efficiency notes: -- Variable: *efficiency-note-cost-threshold* Before printing some efficiency notes, the compiler compares the value of this variable to the difference in cost between the chosen implementation and the best potential implementation. If the difference is not greater than this limit, then no note is printed. The units are implementation dependent; the initial value suppresses notes about "trivial" inefficiencies. A value of `1' will note any inefficiency. -- Variable: *efficiency-note-limit* When printing some efficiency notes, the compiler reports possible efficient implementations. The initial value of `2' prevents excessively long efficiency notes in the common case where there is no type information, so all implementations are possible. File: cmu-user.info Node: Profiling, Prev: Efficiency Notes, Up: Advanced Compiler Use and Efficiency Hints Profiling ========= The first step in improving a program's performance is to profile the activity of the program to find where it spends its time. The best way to do this is to use the profiling utility found in the `profile' package. This package provides a macro `profile' that encapsulates functions with statistics gathering code. * Menu: * Profile Interface:: * Profiling Techniques:: * Nested or Recursive Calls:: * Clock resolution:: * Profiling overhead:: * Additional Timing Utilities:: * A Note on Timing:: * Benchmarking Techniques:: File: cmu-user.info Node: Profile Interface, Prev: Profiling, Up: Profiling, Next: Profiling Techniques Profile Interface ----------------- -- Variable: *timed-functions* This variable holds a list of all functions that are currently being profiled. -- Macro: profile {NAME}* This macro wraps profiling code around the named functions. As in `trace', the NAMEs are not evaluated. If a function is already profiled, then the function is unprofiled and reprofiled (useful to notice function redefinition.) A warning is printed for each name that is not a defined function. -- Macro: unprofile {NAME}* This macro removes profiling code from the named functions. If no NAMEs are supplied, all currently profiled functions are unprofiled. -- Macro: report-time {NAME}* This macro prints a report for each NAMEd function of the following information: * The total CPU time used in that function for all calls, * the total number of bytes consed in that function for all calls, * the total number of calls, * the average amount of CPU time per call. Summary totals of the CPU time, consing and calls columns are printed. An estimate of the profiling overhead is also printed (see below). If no NAMEs are supplied, then the times for all currently profiled functions are printed. -- Macro: reset-time {NAME}* This macro resets the profiling counters associated with the NAMEd functions. If no NAMEs are supplied, then all currently profiled functions are reset. File: cmu-user.info Node: Profiling Techniques, Prev: Profile Interface, Up: Profiling, Next: Nested or Recursive Calls Profiling Techniques -------------------- Start by profiling big pieces of a program, then carefully choose which functions close to, but not in, the inner loop are to be profiled next. Avoid profiling functions that are called by other profiled functions, since this opens the possibility of profiling overhead being included in the reported times. If the per-call time reported is less than 1/10 second, then consider the clock resolution and profiling overhead before you believe the time. It may be that you will need to run your program many times in order to average out to a higher resolution. File: cmu-user.info Node: Nested or Recursive Calls, Prev: Profiling Techniques, Up: Profiling, Next: Clock resolution Nested or Recursive Calls ------------------------- The profiler attempts to compensate for nested or recursive calls. Time and consing overhead will be charged to the dynamically innermost (most recent) call to a profiled function. So profiling a subfunction of a profiled function will cause the reported time for the outer function to decrease. However if an inner function has a large number of calls, some of the profiling overhead may "leak" into the reported time for the outer function. In general, be wary of profiling short functions that are called many times. File: cmu-user.info Node: Clock resolution, Prev: Nested or Recursive Calls, Up: Profiling, Next: Profiling overhead Clock resolution ---------------- Unless you are very lucky, the length of your machine's clock "tick" is probably much longer than the time it takes simple function to run. For example, on the IBM RT, the clock resolution is 1/50 second. This means that if a function is only called a few times, then only the first couple decimal places are really meaningful. Note however, that if a function is called many times, then the statistical averaging across all calls should result in increased resolution. For example, on the IBM RT, if a function is called a thousand times, then a resolution of tens of microseconds can be expected. File: cmu-user.info Node: Profiling overhead, Prev: Clock resolution, Up: Profiling, Next: Additional Timing Utilities Profiling overhead ------------------ The added profiling code takes time to run every time that the profiled function is called, which can disrupt the attempt to collect timing information. In order to avoid serious inflation of the times for functions that take little time to run, an estimate of the overhead due to profiling is subtracted from the times reported for each function. Although this correction works fairly well, it is not totally accurate, resulting in times that become increasingly meaningless for functions with short runtimes. This is only a concern when the estimated profiling overhead is many times larger than reported total CPU time. The estimated profiling overhead is not represented in the reported total CPU time. The sum of total CPU time and the estimated profiling overhead should be close to the total CPU time for the entire profiling run (as determined by the `time' macro.) Time unaccounted for is probably being used by functions that you forgot to profile. File: cmu-user.info Node: Additional Timing Utilities, Prev: Profiling overhead, Up: Profiling, Next: A Note on Timing Additional Timing Utilities --------------------------- -- Macro: time FORM This macro evaluates FORM, prints some timing and memory allocation information to `*trace-output*', and returns any values that FORM returns. The timing information includes real time, user run time, and system run time. This macro executes a form and reports the time and consing overhead. If the `time' form is not compiled (e.g. it was typed at top-level), then `compile' will be called on the form to give more accurate timing information. If you really want to time interpreted speed, you can say: (time (eval 'FORM)) Things that execute fairly quickly should be timed more than once, since there may be more paging overhead in the first timing. To increase the accuracy of very short times, you can time multiple evaluations: (time (dotimes (i 100) FORM)) -- Function: get-bytes-consed This function returns the number of bytes allocated since the first time you called it. The first time it is called it returns zero. The above profiling routines use this to report consing information. -- Variable: *gc-run-time* This variable accumulates the run-time consumed by garbage collection, in the units returned by get-internal-run-time. -- Constant: internal-time-units-per-second The value of internal-time-units-per-second is 100. File: cmu-user.info Node: A Note on Timing, Prev: Additional Timing Utilities, Up: Profiling, Next: Benchmarking Techniques A Note on Timing ---------------- There are two general kinds of timing information provided by the `time' macro and other profiling utilities: real time and run time. Real time is elapsed, wall clock time. It will be affected in a fairly obvious way by any other activity on the machine. The more other processes contending for CPU and memory, the more real time will increase. This means that real time measurements are difficult to replicate, though this is less true on a dedicated workstation. The advantage of real time is that it is real. It tells you really how long the program took to run under the benchmarking conditions. The problem is that you don't know exactly what those conditions were. Run time is the amount of time that the processor supposedly spent running the program, as opposed to waiting for I/O or running other processes. "User run time" and "system run time" are numbers reported by the Unix kernel. They are supposed to be a measure of how much time the processor spent running your "user" program (which will include GC overhead, etc.), and the amount of time that the kernel spent running "on your behalf". Ideally, user time should be totally unaffected by benchmarking conditions; in reality user time does depend on other system activity, though in rather non-obvious ways. System time will clearly depend on benchmarking conditions. In Lisp benchmarking, paging activity increases system run time (but not by as much as it increases real time, since the kernel spends some time waiting for the disk, and this is not run time, kernel or otherwise.) In my experience, the biggest trap in interpreting kernel/user run time is to look only at user time. In reality, it seems that the SUM of kernel and user time is more reproducible. The problem is that as system activity increases, there is a spurious DECREASE in user run time. In effect, as paging, etc., increases, user time leaks into system time. So, in practice, the only way to get truly reproducible results is to run with the same competing activity on the system. Try to run on a machine with nobody else logged in, and check with "ps aux" to see if there are any system processes munching large amounts of CPU or memory. If the ratio between real time and the sum of user and system time varies much between runs, then you have a problem. File: cmu-user.info Node: Benchmarking Techniques, Prev: A Note on Timing, Up: Profiling Benchmarking Techniques ----------------------- Given these imperfect timing tools, how do should you do benchmarking? The answer depends on whether you are trying to measure improvements in the performance of a single program on the same hardware, or if you are trying to compare the performance of different programs and/or different hardware. For the first use (measuring the effect of program modifications with constant hardware), you should look at BOTH system+user and real time to understand what effect the change had on CPU use, and on I/O (including paging.) If you are working on a CPU intensive program, the change in system+user time will give you a moderately reproducible measure of performance across a fairly wide range of system conditions. For a CPU intensive program, you can think of system+user as "how long it would have taken to run if I had my own machine." So in the case of comparing CPU intensive programs, system+user time is relatively real, and reasonable to use. For programs that spend a substantial amount of their time paging, you really can't predict elapsed time under a given operating condition without benchmarking in that condition. User or system+user time may be fairly reproducible, but it is also relatively meaningless, since in a paging or I/O intensive program, the program is spending its time waiting, not running, and system time and user time are both measures of run time. A change that reduces run time might increase real time by increasing paging. Another common use for benchmarking is comparing the performance of the same program on different hardware. You want to know which machine to run your program on. For comparing different machines (operating systems, etc.), the only way to compare that makes sense is to set up the machines in EXACTLY the way that they will NORMALLY be run, and then measure REAL time. If the program will normally be run along with X, then run X. If the program will normally be run on a dedicated workstation, then be sure nobody else is on the benchmarking machine. If the program will normally be run on a machine with three other Lisp jobs, then run three other Lisp jobs. If the program will normally be run on a machine with 8meg of memory, then run with 8meg. Here, "normal" means "normal for that machine". If you the choice of an unloaded RT or a heavily loaded PMAX, do your benchmarking on an unloaded RT and a heavily loaded PMAX. If you have a program you believe to be CPU intensive, then you might be tempted to compare "run" times across systems, hoping to get a meaningful result even if the benchmarking isn't done under the expected running condition. Don't to this, for two reasons: * The operating systems might not compute run time in the same way. * Under the real running condition, the program might not be CPU intensive after all. In the end, only real time means anything -- it is the amount of time you have to wait for the result. The only valid uses for run time are: * To develop insight into the program. For example, if run time is much less than elapsed time, then you are probably spending lots of time paging. * To evaluate the relative performance of CPU intensive programs in the same environment. File: cmu-user.info Node: UNIX Interface, Prev: Advanced Compiler Use and Efficiency Hints, Up: Top, Next: Event Dispatching with SERVE-EVENT UNIX Interface ************** By Robert MacLachlan, Skef Wholey, Bill Chiles, and William Lott CMU Common Lisp attempts to make the full power of the underlying environment available to the Lisp programmer. This is done using combination of hand-coded interfaces and foreign function calls to C libraries. Although the techniques differ, the style of interface is similar. This chapter provides an overview of the facilities available and general rules for using them, as well as describing specific features in detail. It is assumed that the reader has a working familiarity with Mach, Unix and X, as well as access to the standard system documentation. * Menu: * Reading the Command Line:: * Lisp Equivalents for C Routines:: * Type Translations:: * System Area Pointers:: * Unix System Calls:: * File Descriptor Streams:: * Making Sense of Mach Return Codes:: * Unix Interrupts:: File: cmu-user.info Node: Reading the Command Line, Prev: UNIX Interface, Up: UNIX Interface, Next: Useful Variables Reading the Command Line ======================== The shell parses the command line with which Lisp is invoked, and passes a data structure containing the parsed information to Lisp. This information is then extracted from that data structure and put into a set of Lisp data structures. -- Variable: *command-line-strings* -- Variable: *command-line-utility-name* -- Variable: *command-line-words* -- Variable: *command-line-switches* The value of `*command-line-words*' is a list of strings that make up the command line, one word per string. The first word on the command line, i.e. the name of the program invoked (usually `lisp') is stored in `*command-line-utility-name*'. The value of `*command-line-switches*' is a list of `command-line-switch' structures, with a structure for each word on the command line starting with a hyphen. All the command line words between the program name and the first switch are stored in `*command-line-words*'. The following functions may be used to examine `command-line-switch' structures. -- Function: cmd-switch-name SWITCH Returns the name of the switch, less the preceding hyphen and trailing equal sign (if any). -- Function: cmd-switch-value SWITCH Returns the value designated using an embedded equal sign, if any. If the switch has no equal sign, then this is null. -- Function: cmd-switch-words SWITCH Returns a list of the words between this switch and the next switch or the end of the command line. File: cmu-user.info Node: Useful Variables, Prev: Reading the Command Line, Up: UNIX Interface, Next: Lisp Equivalents for C Routines Useful Variables ================ -- Variable: *stdin* -- Variable: *stdout* -- Variable: *stderr* Streams connected to the standard input, output and error file descriptors. -- Variable: *tty* A stream connected to `/dev/tty'. -- Variable: *task-self* -- Variable: *task-data* -- Variable: *task-notify* The initial ports for the Lisp process (Mach only.) File: cmu-user.info Node: Lisp Equivalents for C Routines, Prev: Useful Variables, Up: UNIX Interface, Next: Type Translations Lisp Equivalents for C Routines =============================== The UNIX documentation describes the system interface in terms of C procedure headers. The corresponding Lisp function will have a somewhat different interface, since Lisp argument passing conventions and datatypes are different. The main difference in the argument passing conventions is that Lisp does not support passing values by reference. In Lisp, all argument and results are passed by value. Interface functions take some fixed number of arguments and return some fixed number of values. A given "parameter" in the C specification will appear as an argument, return value, or both, depending on whether it is an In parameter, Out parameter, or In/Out parameter. The basic transformation one makes to come up with the Lisp equivalent of a C routine is to remove the Out parameters from the call, and treat them as extra return values. In/Out parameters appear both as arguments and return values. Since Out and In/Out parameters are only conventions in C, you must determine the usage from the documentation. Thus, the C routine declared as kern_return_t lookup(servport, portsname, portsid) port servport; char *portsname; int *portsid; /* out */ { ... *portsid = <expression to compute portsid field> return(KERN_SUCCESS); } has as its Lisp equivalent something like (defun lookup (ServPort PortsName) ... (values success <expression to compute portsid field>)) If there are multiple out or in-out arguments, then there are multiple additional returns values. Fortunately, CMU Common Lisp programmers rarely have to worry about the nuances of this translation process, since the names of the arguments and return values are documented in a way so that the `describe' function (and the Hemlock `Describe Function Call' command, invoked with C-M-Shift-A) will list this information. Since the names of arguments and return values are usually descriptive, the information that `describe' prints is usually all one needs to write a call. Most programmers use this on-line documentation nearly all of the time, and thereby avoid the need to handle bulky manuals and perform the translation from barbarous tongues. File: cmu-user.info Node: Type Translations, Prev: Lisp Equivalents for C Routines, Up: UNIX Interface, Next: System Area Pointers Type Translations ================= Lisp data types have very different representations from those used by conventional languages such as C. Since the system interfaces are designed for conventional languages, Lisp must translate objects to and from the Lisp representations. Many simple objects have a direct translation: integers, characters, strings and floating point numbers are translated to the corresponding Lisp object. A number of types, however, are implemented differently in Lisp for reasons of clarity and efficiency. Instances of enumerated types are expressed as keywords in Lisp. Records, arrays, and pointer types are implemented with the Alien facility (see page ?.) Access functions are defined for these types which convert fields of records, elements of arrays, or data referenced by pointers into Lisp objects (possibly another object to be referenced with another access function). One should dispose of Alien objects created by constructor functions or returned from remote procedure calls when they are no longer of any use, freeing the virtual memory associated with that object. Since aliens contain pointers to non-Lisp data, the garbage collector cannot do this itself. If the memory was obtained from make-alien ? or from a foreign function call to a routine that used `malloc', then free-alien ? should be used. If the alien was created using MACH memory allocation (e.g. `vm_allocate'), then the storage should be freed using `vm_deallocate'. File: cmu-user.info Node: System Area Pointers, Prev: Type Translations, Up: UNIX Interface, Next: Unix System Calls System Area Pointers ==================== Note that in some cases an address is represented by a Lisp integer, and in other cases it is represented by a real pointer. Pointers are usually used when an object in the current address space is being referred to. The MACH virtual memory manipulation calls must use integers, since in principle the address could be in any process, and Lisp cannot abide random pointers. Because these types are represented differently in Lisp, one must explicitly coerce between these representations. System Area Pointers (SAPs) provide a mechanism that bypasses the Alien type system and accesses virtual memory directly. A SAP is a raw byte pointer into the `lisp' process address space. SAPs are represented with a pointer descriptor, so SAP creation can cause consing. However, the compiler uses a non-descriptor representation for SAPs when possible, so the consing overhead is generally minimal. *Note Non-Descriptor Representations::. -- Function: sap-int SAP -- Function: int-sap INT The function `sap-int' is used to generate an integer corresponding to the system area pointer, suitable for passing to the kernel interfaces (which want all addresses specified as integers). The function `int-sap' is used to do the opposite conversion. The integer representation of a SAP is the byte offset of the SAP from the start of the address space. -- Function: sap+ SAP OFFSET This function adds a byte OFFSET to SAP, returning a new SAP. -- Function: sap-ref-8 SAP OFFSET -- Function: sap-ref-16 SAP OFFSET -- Function: sap-ref-32 SAP OFFSET These functions return the 8, 16 or 32 bit unsigned integer at OFFSET from SAP. The OFFSET is always a byte offset, regardless of the number of bits accessed. `setf' may be used with the these functions to deposit values into virtual memory. -- Function: signed-sap-ref-8 SAP OFFSET -- Function: signed-sap-ref-16 SAP OFFSET -- Function: signed-sap-ref-32 SAP OFFSET These functions are the same as the above unsigned operations, except that they sign-extend, returning a negative number if the high bit is set. File: cmu-user.info Node: Unix System Calls, Prev: System Area Pointers, Up: UNIX Interface, Next: File Descriptor Streams Unix System Calls ================= You probably won't have much cause to use them, but all the Unix system calls are available. The Unix system call functions are in the `Unix' package. The name of the interface for a particular system call is the name of the system call prepended with `unix-'. The system usually defines the associated constants without any prefix name. To find out how to use a particular system call, try using `describe' on it. If that is unhelpful, look at the source in `syscall.lisp' or consult your system maintainer. The Unix system calls indicate an error by returning false as the first value and the Unix error number as the second value. If the call succeeds, then the first value will always be non-nil, often `t'. -- Function: get-unix-error-msg ERROR This function returns a string describing the Unix error number ERROR. File: cmu-user.info Node: File Descriptor Streams, Prev: Unix System Calls, Up: UNIX Interface, Next: Making Sense of Mach Return Codes File Descriptor Streams ======================= Many of the UNIX system calls return file descriptors. Instead of using other UNIX system calls to perform I/O on them, you can create a stream around them. For this purpose, fd-streams exist. -- Function: make-fd-stream DESCRIPTOR &keys :input :output :element-type :buffering :name :file :original :delete-original :auto-close :timeout This function creates a file descriptor stream using DESCRIPTOR. If INPUT is non-nil, input operations are allowed. If OUTPUT is non-nil, output operations are allowed. The default is input only. These keywords are defined: ELEMENT-TYPE is the type of the unit of transaction for the stream, which defaults to `string-char'. See the Common Lisp description of `open' for valid values. BUFFERING is the kind of output buffering desired for the stream. Legal values are :none for no buffering, :line for buffering up to each newline, and :full for full buffering. NAME is a simple-string name to use for descriptive purposes when the system prints an fd-stream. When printing fd-streams, the system prepends the streams name with `Stream for '. If NAME is unspecified, it defaults to a string containing FILE or DESCRIPTOR, in order of preference. FILE, ORIGINAL : FILE specifies the name of the associated file when creating a file stream (must be a `simple-string'). ORIGINAL is the `simple-string' name of a backup file containing the original contents of FILE while writing FILE. When you abort the stream by passing true to `close' as the second argument, if you supplied both FILE and ORIGINAL, `close' will rename the ORIGINAL name to the FILE name. When you `close' the stream normally, if you supplied ORIGINAL, and DELETE-ORIGINAL is non-nil, `close' deletes ORIGINAL. If AUTO-CLOSE is true (the default), then DESCRIPTOR will be closed when the stream is garbage collected. TIMEOUT if non-null, then TIMEOUT is an integer number of seconds after which an input wait should time out. If a read does time out, then the `system:io-timeout' condition is signalled. -- Function: fd-stream-p OBJECT This function returns true if OBJECT is an fd-stream, and nil if not. -- Function: fd-stream-fd STREAM This returns the file descriptor associated with STREAM. File: cmu-user.info Node: Making Sense of Mach Return Codes, Prev: File Descriptor Streams, Up: UNIX Interface, Next: Unix Interrupts Making Sense of Mach Return Codes ================================= Whenever a remote procedure call returns a Unix error code (such as `kern_return_t'), it is usually prudent to check that code to see if the call was successful. To relieve the programmer of the hassle of testing this value himself, and to centralize the information about the meaning of non-success return codes, CMU Common Lisp provides a number of macros and functions. See also get-unix-error-msg *Note Unix System Calls::. -- Function: gr-error FUNCTION GR &optional CONTEXT Signals a Lisp error, printing a message indicating that the call to the specified FUNCTION failed, with the return code GR. If supplied, the CONTEXT string is printed after the FUNCTION name and before the string associated with the GR. For example: * (gr-error 'nukegarbage 3 "lost big") Error in function GR-ERROR: NUKEGARBAGE lost big, no space. Proceed cases: 0: Return to Top-Level. Debug (type H for help) (Signal #<Conditions:Simple-Error.5FDE0>) 0] -- Macro: gr-call FUNCTION &rest ARGS -- Macro: gr-call* FUNCTION &rest ARGS These macros can be used to call a function and automatically check the GeneralReturn code and signal an appropriate error in case of non-successful return. `gr-call' returns false if no error occurs, while `gr-call*' returns the second value of the function called. * (gr-call mach:port_allocate *task-self*) NIL * -- Macro: gr-bind `('{VAR}*`)' `('FUNCTION {ARG}*`)' {FORM}* This macro can be used much like `multiple-value-bind' to bind the VARs to return values resulting from calling the FUNCTION with the given ARGs. The first return value is not bound to a variable, but is checked as a GeneralReturn code, as in `gr-call'. * (gr-bind (port_list port_list_cnt) (mach:port_select *task-self*) (format t "The port count is ~S." port_list_cnt) port_list) The port count is 0. #<Alien value> * File: cmu-user.info Node: Unix Interrupts, Prev: Making Sense of Mach Return Codes, Up: UNIX Interface Unix Interrupts =============== CMU Common Lisp allows access to all the Unix signals that can be generated under Unix. It should be noted that if this capability is abused, it is possible to completely destroy the running Lisp. The following macros and functions allow access to the Unix interrupt system. The signal names as specified in section 2 of the Unix Programmer's Manual are exported from the Unix package. * Menu: * Changing Interrupt Handlers:: * Examples of Signal Handlers:: File: cmu-user.info Node: Changing Interrupt Handlers, Prev: Unix Interrupts, Up: Unix Interrupts, Next: Examples of Signal Handlers Changing Interrupt Handlers --------------------------- -- Macro: with-enabled-interrupts SPECS &rest BODY This macro should be called with a list of signal specifications, SPECS. Each element of SPECS should be a list of two elements: the first should be the Unix signal for which a handler should be established, the second should be a function to be called when the signal is received One or more signal handlers can be established in this way. `with-enabled-interrupts' establishes the correct signal handlers and then executes the forms in BODY. The forms are executed in an unwind-protect so that the state of the signal handlers will be restored to what it was before the `with-enabled-interrupts' was entered. A signal handler function specified as NIL will set the Unix signal handler to the default which is normally either to ignore the signal or to cause a core dump depending on the particular signal. -- Macro: without-interrupts &rest BODY It is sometimes necessary to execute a piece a code that can not be interrupted. This macro the forms in BODY with interrupts disabled. Note that the Unix interrupts are not actually disabled, rather they are queued until after BODY has finished executing. -- Macro: with-interrupts &rest BODY When executing an interrupt handler, the system disables interrupts, as if the handler was wrapped in in a `without-interrupts'. The macro `with-interrupts' can be used to enable interrupts while the forms in BODY are evaluated. This is useful if BODY is going to enter a break loop or do some long computation that might need to be interrupted. -- Macro: without-hemlock &rest BODY For some interrupts, such as SIGTSTP (suspend the Lisp process and return to the Unix shell) it is necessary to leave Hemlock and then return to it. This macro executes the forms in BODY after exiting Hemlock. When BODY has been executed, control is returned to Hemlock. -- Function: enable-interrupt SIGNAL FUNCTION This function establishes FUNCTION as the handler for SIGNAL. Unless you want to establish a global signal handler, you should use the macro `with-enabled-interrupts' to temporarily establish a signal handler. `enable-interrupt' returns the old function associated with the signal. -- Function: ignore-interrupt SIGNAL Ignore-interrupt sets the Unix signal mechanism to ignore SIGNAL which means that the Lisp process will never see the signal. Ignore-interrupt returns the old function associated with the signal or false if none is currently defined. -- Function: default-interrupt SIGNAL Default-interrupt can be used to tell the Unix signal mechanism to perform the default action for SIGNAL. For details on what the default action for a signal is, see section 2 of the Unix Programmer's Manual. In general, it is likely to ignore the signal or to cause a core dump. File: cmu-user.info Node: Examples of Signal Handlers, Prev: Changing Interrupt Handlers, Up: Unix Interrupts Examples of Signal Handlers --------------------------- The following code is the signal handler used by the Lisp system for the SIGINT signal. (defun ih-sigint (signal code scp) (declare (ignore signal code scp)) (without-hemlock (with-interrupts (break "Software Interrupt" t)))) The `without-hemlock' form is used to make sure that Hemlock is exited before a break loop is entered. The `with-interrupts' form is used to enable interrupts because the user may want to generate an interrupt while in the break loop. Finally, break is called to enter a break loop, so the user can look at the current state of the computation. If the user proceeds from the break loop, the computation will be restarted from where it was interrupted. The following function is the Lisp signal handler for the SIGTSTP signal which suspends a process and returns to the Unix shell. (defun ih-sigtstp (signal code scp) (declare (ignore signal code scp)) (without-hemlock (Unix:unix-kill (Unix:unix-getpid) Unix:sigstop))) Lisp uses this interrupt handler to catch the SIGTSTP signal because it is necessary to get out of Hemlock in a clean way before returning to the shell. To set up these interrupt handlers, the following is recommended: (with-enabled-interrupts ((Unix:SIGINT #'ih-sigint) (Unix:SIGTSTP #'ih-sigtstp)) <user code to execute with the above signal handlers enabled.> ) File: cmu-user.info Node: Event Dispatching with SERVE-EVENT, Prev: UNIX Interface, Up: Top, Next: Alien Objects Event Dispatching with SERVE-EVENT ********************************** By Bill Chiles and Robert MacLachlan It is common to have multiple activities simultaneously operating in the same Lisp process. Furthermore, Lisp programmers tend to expect a flexible development environment. It must be possible to load and modify application programs without requiring modifications to other running programs. CMU Common Lisp achieves this by having a central scheduling mechanism based on an event-driven, object-oriented paradigm. An EVENT is some interesting happening that should cause the Lisp process to wake up and do something. These events include X events and activity on Unix file descriptors. The object-oriented mechanism is only available with the first two, and it is optional with X events as described later in this chapter. In an X event, the window ID is the object capability and the X event type is the operation code. The Unix file descriptor input mechanism simply consists of an association list of a handler to call when input shows up on a particular file descriptor. * Menu: * Object Sets:: * The SERVE-EVENT Function:: * Using SERVE-EVENT with Unix File Descriptors:: * Using SERVE-EVENT with the CLX Interface to X:: * A SERVE-EVENT Example:: File: cmu-user.info Node: Object Sets, Prev: Event Dispatching with SERVE-EVENT, Up: Event Dispatching with SERVE-EVENT, Next: The SERVE-EVENT Function Object Sets =========== An object set is a collection of objects that have the same implementation for each operation. Externally the object is represented by the object capability and the operation is represented by the operation code. Within Lisp, the object is represented by an arbitrary Lisp object, and the implementation for the operation is represented by an arbitrary Lisp function. The object set mechanism maintains this translation from the external to the internal representation. -- Function: make-object-set NAME &optional DEFAULT-HANDLER This function makes a new object set. NAME is a string used only for purposes of identifying the object set when it is printed. DEFAULT-HANDLER is the function used as a handler when an undefined operation occurs on an object in the set. You can define operations with the `serve-'OPERATION functions exported the `extensions' package for X events (?). Objects are added with `system:add-xwindow-object'. Initially the object set has no objects and no defined operations. -- Function: object-set-operation OBJECT-SET OPERATION-CODE This function returns the handler function that is the implementation of the operation corresponding to OPERATION-CODE in OBJECT-SET. When set with `setf', the setter function establishes the new handler. The `serve-'OPERATION functions exported from the `extensions' package for X events (?) call this on behalf of the user when announcing a new operation for an object set. -- Function: add-xwindow-object WINDOW OBJECT OBJECT-SET These functions add PORT or WINDOW to OBJECT-SET. OBJECT is an arbitrary Lisp object that is associated with the PORT or WINDOW capability. WINDOW is a CLX window. When an event occurs, `system:serve-event' passes OBJECT as an argument to the handler function. File: cmu-user.info Node: The SERVE-EVENT Function, Prev: Object Sets, Up: Event Dispatching with SERVE-EVENT, Next: Using SERVE-EVENT with Unix File Descriptors The SERVE-EVENT Function ======================== The `system:serve-event' function is the standard way for an application to wait for something to happen. For example, the Lisp system calls `system:serve-event' when it wants input from X or a terminal stream. The idea behind `system:serve-event' is that it knows the appropriate action to take when any interesting event happens. If an application calls `system:serve-event' when it is idle, then any other applications with pending events can run. This allows several applications to run "at the same time" without interference, even though there is only one thread of control. Note that if an application is waiting for input of any kind, then other applications will get events. -- Function: serve-event &optional TIMEOUT This function waits for an event to happen and then dispatches to the correct handler function. If specified, TIMEOUT is the number of seconds to wait before timing out. A time out of zero seconds is legal and causes `system:serve-event' to poll for any events immediately available for processing. `system:serve-event' returns true if it serviced at least one event, and nil otherwise. Depending on the application, when `system:serve-event' returns true, you might want to call it repeatedly with a timeout of zero until it returns nil. If input is available on any designated file descriptor, then this calls the appropriate handler function supplied by `system:add-fd-handler'. Since events for many different applications may arrive simultaneously, an application waiting for a specific event must loop on `system:serve-event' until the desired event happens. Since programs such as hemlock call `system:serve-event' for input, applications usually do not need to call `system:serve-event' at all; hemlock allows other application's handlers to run when it goes into an input wait. -- Function: serve-all-events &optional TIMEOUT This function is similar to `system:serve-event', except it serves all the pending events rather than just one. It returns true if it serviced at least one event, and nil otherwise. File: cmu-user.info Node: Using SERVE-EVENT with Unix File Descriptors, Prev: The SERVE-EVENT Function, Up: Event Dispatching with SERVE-EVENT, Next: Using SERVE-EVENT with the CLX Interface to X Using SERVE-EVENT with Unix File Descriptors ============================================ Object sets are not available for use with file descriptors, as there are only two operations possible on file descriptors: input and output. Instead, a handler for either input or output can be registered with `system:serve-event' for a specific file descriptor. Whenever any input shows up, or output is possible on this file descriptor, the function associated with the handler for that descriptor is funcalled with the descriptor as it's single argument. -- Function: add-fd-handler fd direction function This function installs and returns a new handler for the file descriptor FD. DIRECTION can be either :input if the system should invoke the handler when input is available or :output if the system should invoke the handler when output is possible. This returns a unique object representing the handler, and this is a suitable argument for `system:remove-fd-handler' FUNCTION must take one argument, the file descriptor. -- Function: remove-fd-handler HANDLER This function removes HANDLER, that `add-fd-handler' must have previously returned. -- Macro: with-fd-handler (direction fd function) {FORM}* This macro executes the supplied forms with a handler installed using FD, DIRECTION, and FUNCTION. See `system:add-fd-handler'. -- Function: wait-until-fd-usable direction fd &optional TIMEOUT This function waits for up to TIMEOUT seconds for FD to become usable for DIRECTION (either :input or :output). If TIMEOUT is nil or unspecified, this waits forever. -- Function: invalidate-descriptor FD This function removes all handlers associated with FD. This should only be used in drastic cases (such as I/O errors, but not necessarily EOF). Normally, you should use `remove-fd-handler' to remove the specific handler. File: cmu-user.info Node: Using SERVE-EVENT with the CLX Interface to X, Prev: Using SERVE-EVENT with Unix File Descriptors, Up: Event Dispatching with SERVE-EVENT, Next: A SERVE-EVENT Example Using SERVE-EVENT with the CLX Interface to X ============================================= Remember from section *Note Object Sets::, an object set is a collection of objects, CLX windows in this case, with some set of operations, event keywords, with corresponding implementations, the same handler functions. Since X allows multiple display connections from a given process, you can avoid using object sets if every window in an application or display connection behaves the same. If a particular X application on a single display connection has windows that want to handle certain events differently, then using object sets is a convenient way to organize this since you need some way to map the window/event combination to the appropriate functionality. The following is a discussion of functions exported from the `extensions' package that facilitate handling CLX events through `system:serve-event'. The first two routines are useful regardless of whether you use `system:serve-event': -- Function: open-clx-display &optional STRING This function parses STRING for an X display specification including display and screen numbers. STRING defaults to the following: (cdr (assoc :display ext:*environment-list* :test #'eq)) If any field in the display specification is missing, this signals an error. `ext:open-clx-display' returns the CLX display and screen. -- Function: flush-display-events DISPLAY This function flushes all the events in DISPLAY's event queue including the current event, in case the user calls this from within an event handler. * Menu: * Without Object Sets:: * With Object Sets:: File: cmu-user.info Node: Without Object Sets, Prev: Using SERVE-EVENT with the CLX Interface to X, Up: Using SERVE-EVENT with the CLX Interface to X, Next: With Object Sets Without Object Sets ------------------- Since most applications that use CLX, can avoid the complexity of object sets, these routines are described in a separate section. The routines described in the next section that use the object set mechanism are based on these interfaces. -- Function: enable-clx-event-handling DISPLAY HANDLER This function causes `system:serve-event' to notice when there is input on DISPLAY's connection to the X11 server. When this happens, `system:serve-event' invokes HANDLER on DISPLAY in a dynamic context with an error handler bound that flushes all events from DISPLAY and returns. By returning, the error handler declines to handle the error, but it will have cleared all events; thus, entering the debugger will not result in infinite errors due to streams that wait via `system:serve-event' for input. Calling this repeatedly on the same DISPLAY establishes HANDLER as a new handler, replacing any previous one for DISPLAY. -- Function: disable-clx-event-handling DISPLAY This function undoes the effect of `ext:enable-clx-event-handling'. -- Macro: with-clx-event-handling (DISPLAY HANDLER) {form}* This macro evaluates each FORM in a context where `system:serve-event' invokes HANDLER on DISPLAY whenever there is input on DISPLAY's connection to the X server. This destroys any previously established handler for DISPLAY.